| Internet-Draft | OAuth native clients with wallet present | January 2026 |
| Zehavi | Expires 11 July 2026 | [Page] |
OAuth 2.0 for First-Party Applications (FiPA) [I-D.ietf-oauth-first-party-apps] 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.¶
OpenID for Verifiable Presentations [OpenID4VP] does not issue traditional OAuth tokens as its primary output. Its main result is rather a VP Token that carries one or more Verifiable Presentations.¶
This document is an extension profile of FiPA, describing a flow in which authorization server's requirements are met by means of a wallet presentation. It combines a OpenID4VP [OpenID4VP] presentation with FiPA direct authorization server interaction. The proposed flow demonstrates how a wallet presentation could be used by an authorization server to accomplish a login flow, as well as to obtain user's approval to a RAR [RFC9396] payload presented by a wallet when sent as OpenID4VP transaction_data.¶
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://yaron-zehavi.github.io/oauth-native-clients-direct-interation-with-wallet-presentation/draft-zehavi-oauth-native-clients-direct-interation-with-wallet-presentation.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-zehavi-oauth-native-clients-direct-interation-with-wallet-presentation/.¶
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/yaron-zehavi/oauth-native-clients-direct-interation-with-wallet-presentation.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 11 July 2026.¶
Copyright (c) 2026 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.¶
This document, OAuth 2.0 direct interation for native clients using wallet presentation, extends FiPA [I-D.ietf-oauth-first-party-apps] by employ a wallet presentation to satisfy authorization server's requirements.¶
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.¶
Digital credentials stored in wallets may be used by authorization servers to authenticate a user or approve a transaction. This document provides an example flow of how wallet credential presentation is incorporated into FiPA [I-D.ietf-oauth-first-party-apps].¶
We cover 3 primary use cases:¶
This document extends FiPA's [I-D.ietf-oauth-first-party-apps] error response, by adding the following response attributes, used when error code "insufficient_authorization" is returned:¶
IANA has (TBD) registered the following values in the IANA "OAuth Parameters" registry of [IANA.oauth-parameters] established by [RFC6749].¶
Parameter name: native_callback_uri¶
Parameter usage location: Native Authorization Endpoint¶
Change Controller: IETF¶
Specification Document: Section 5.4 of this specification¶
This section provides non-normative examples of how this specification may be used to support specific use cases.¶
Digital credentials (stored in wallets) may be used by authorization servers to authenticate a user or approve a transaction. This example flow shows how wallet credential presentation can be incorporated into this spec using the DC API [DC.API] Or OpenID4VP directly [OpenID4VP].¶
User First Party Client AS Wallet/DC API Verifier ---- ------------------ --- -------------- -------- | | | | | | | | | | | (1) Start Flow | | | | |-------------------->| | | | | | (2) Native Authorization Request | | | |----------------->| | | | | (3) Authorization Error Response | | | | (insufficient_authorization, | | | | dc_credential_required) | | | |<-----------------| | | | | | | | +===================== DC API branch ============================================+ | | (4) Presentation Request (OID4VP) | | | |-------------------------------------->| | | | (5) Presentation Response (vp_token) | | | |<--------------------------------------| | | | (6) vp_token | | | |----------------->| | | | | | (7) vp_token | | | | |-------------------------------------->| | | | (8) Verification Result | | | |<--------------------------------------| +================================================================================+ +=================== No DC API branch ===========================================+ |------- Same device path -------------------------------------------------------| | | (9) Invoke Wallet via Deeplink | | | |-------------------------------------->| | | | | | (10) Presentation Response (vp_token) | | | |----------------->| | | | (11) redirect_uri_client?handle | | | |<--------------------------------------| | | (12) Redirect to client w/ openid4vp_redirect_uri?handle=123 | |<--------------------------------------| | | | (13) Handle | | | |----------------->| | | | | | (14) Get Presentation Result | | | |-------------------------------------->| | | | (15) Presentation Result | | | |<--------------------------------------| |------- Cross device path ------------------------------------------------------| | (16) Display QR Code| | | | |<--------------------| | | | | (17) Scan QR Code | | | | |----------------------------------------------------------->>| | | | | | (18) Presentation Response (vp_token) | | | |----------------->| | +---- Loop ------------------------------------------------+ | | (19) Poll for authorization response | | |----------------->| | | | | (20) Get Presentation Result | | | |<------------------------------------->| | | | (21) Pending | | | |<--------------------------------------| | | (22) Pending | | | |<-----------------| | | +---- Break when presentation done ------------------------| | | | (23) Presentation Result | | | |<--------------------------------------| +================================================================================+ | | | | Note: Assuming the happy path. In case of error, error responses are sent back accordingly. | | | | | (24) Code | | |<-----------------| | | (25) Token Request w/ code | |----------------->| | | (26) Tokens | | |<-----------------| | | |¶
The verifier is displayed here as a separate instance, but can also be part of the authorization server. In both cases, it is transparent to the client, as the client only talks to the authorization server's Native Authorization Endpoint.¶
User opens app¶
The client indicates, as part of the Native Authorization Request, the following:¶
Login via digital credentials (wallet) desired¶
DC API support¶
Same device/cross device (only, if DC API is not supported)¶
a redirect URI intended for redirect from a wallet to the client in [OpenID4VP] same device flows (hereafter called openid4vp_redirect_uri)¶
POST /native-authorization HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded &client_id=bb16c14c73415 &scope=profile &dc_api=false &login_hint=wallet &openid4vp_flow_type=same_device &openid4vp_redirect_uri=https%3A%2F%2Fdeeplink.example.client¶
Note that the client may collect this information from the user before making the initial request, or provide what it knows initially and respond gradually to additional requests for information from the authorization server.¶
Authorization server returns with error response (insufficient_authorization), indicating in the response body that digital credential presentation is required. The authorization server's response may look like this:¶
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
{
"error": "insufficient_authorization",
"auth_session": "ce6772f5e07bc8361572f",
"type": "digital_credentials",
"credentials_request": "openid4vp://?request_uri=..." // omitted if the authorization server cannot yet return the presentation request
}
¶
Client invokes the DC API.¶
The DC API returns the vp_token to the client¶
Client sends vp_token to the authorization server¶
POST /native-authorization HTTP/1.1
Host: server.example.com
Content-Type: application/json
{
"auth_session": "ce6772f5e07bc8361572f",
"vp_token": "....."
}
¶
The authorization server asks the verifier to verify the vp_token¶
The verifier verifies the vp_token and returns the result. The authorization server evaluates the verification result and returns either a code or an error. Here we assume the happy path. Continue with step 24.¶
If DC API is NOT supported and in case of same device flow, the client invokes the Wallet through Deep Link.¶
Wallet presents credentials to verifier.¶
Verifier responds with a redirect_uri instructing wallet to redirect as per [OpenID4VP] section 13.3.¶
Wallet redirects back to the client using the received redirect_uri.¶
Client extracts the response_code and provides it to the authorization server.¶
POST /native-authorization HTTP/1.1
Host: server.example.com
Content-Type: application/json
{
"auth_session": "ce6772f5e07bc8361572f",
"response_code" : "87248924n2f",
}
¶
The authorization server uses the handle at verifier to look retrieve the presentation result.¶
The verifier responds with the presentation result which the authorization server evaluates, then returns either a code or an error. Here we assume the happy path. Continue with step 24.¶
If DC API is NOT supported and in case of cross device, the client renders the presentation request as QR code and displays it to the user.¶
The user scans the QR code with the wallet.¶
The wallet presents the credentials to the verifier.¶
Meanwhile, client polls the authorization server for the presentation status until it receives a non-pending result.¶
POST /native-authorization HTTP/1.1
Host: server.example.com
Content-Type: application/json
{
"auth_session": "ce6772f5e07bc8361572f"
}
¶
The authorization server in turn retreives the presentation status from the verifier.¶
The verifier responds to the authorization server that the presentation result is not yet ready.¶
The authorization server responds to the client that the presentation result is not yet ready.¶
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
{
"error": "insufficient_authorization",
"status": "pending",
"auth_session": "ce6772f5e07bc8361572f"
}
¶
Once the presentation is done, the verifier returns the result to the authorization server, which then evaluates the verification result and returns either a code or an error, breaking the loop. Here we assume the happy path. Continue with step 24.¶
The authorization server returns an authorization code to the client.¶
The client redeems the code for an access token.¶
The authorization server responds to the token request.¶
[OpenID4VP] supports transaction data, which is additional data to be signed and presented alongside the requested credentials. This can be mapped to RAR [RFC9396]. The following diagram depicts a wallet flow incorporating RAR. Details of how the wallet is invoked or how the presentation result reaches the authorization server are omitted for simplicity. Refer to Appendix A.1 for details.¶
First Party Client AS Wallet/DC API Verifier ------------------ --- -------------- -------- | | | | | (1) Native Authorization Request w/ RAR | | |------------------------->| | | | | (2) Create Presentation request (OIDC4VP) w/ tx_data | |-------------------------------------->| | | (3) Presentation request (OIDC4VP) | | |<--------------------------------------| | (4) Presentation request (OIDC4VP) | | |<-------------------------| | | | (5) Presentation Request (OIDC4VP) | | |---------------------------------------------->| | | | | (6) Presentation Response (vp_token) | | |----------------->| | | (7) Presentation Result | | |<--------------------------------------| | (8) code | |<-------------------------| | (9) Token Request w/ code |------------------------->| | (10) Token Response w/ RAR |<-------------------------|¶
The client initiates the OAuth request, including RAR.¶
The authorization server processes that RAR from the request and creates a transaction data object from it. The authorization server then sends a request including the transaction data to the verifier to create a presentation request.¶
The verifier responds with the presentation request.¶
The authorization server responds to client with the presentation request.¶
The client invokes the wallet. How exactly the wallet is invoked is omitted for simplicity. See Usage with Digital Credentials Appendix A.1 for details.¶
The wallet creates a vp_token including the requested transaction data and sends it to the verifier.¶
The verifier verifies the vp_token and eventually the authorization server learns about the result. How the authorization server learns about the result is omitted for simplicity. See Usage with Digital Credentials Appendix A.1 for details. The authorization server then evaluates the result, especially the transaction data.¶
The authorization server returns an authorization code to the client.¶
The client redeems the code for an access token.¶
The authorization server responds to the token request. It also includes the authorization_details.¶
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"token_type": "Bearer",
"expires_in": 3600,
"authorization_details": [
{
"type": "account_information",
"access": {
"accounts": [
{
"iban": "DE2310010010123456789"
},
{
"maskedPan": "123456xxxxxx1234"
}
],
"balances": [
{
"iban": "DE2310010010123456789"
}
],
"transactions": [
{
"iban": "DE2310010010123456789"
},
{
"maskedPan": "123456xxxxxx1234"
}
]
},
"recurringIndicator": true
}
]
}
¶
-00¶
Document creation¶
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.¶