add `redirect_uri` to Credential Offer by paulbastian · Pull Request #759 · openid/OpenID4VCI

paulbastian · 2026-06-18T18:42:19Z

Replaces #723

discuss whether to use SHOULD or MAY to open redirect_uri
make editorial changes to fix grants text in Credential Offer Parameters in 1.0?
discuss whether expected_redirect_origins should be origins or paths

paulbastian · 2026-06-22T08:39:26Z

+  * `authorization_code`: OPTIONAL. Object for the Authorization Code Grant type.
+    * `issuer_state`: OPTIONAL. String value created by the Credential Issuer and opaque to the Wallet that is used to bind the subsequent Authorization Request with a context set up during previous process steps. If the Wallet decides to use the Authorization Code Flow and received a value for this parameter, it MUST include it in the subsequent Authorization Request to the Authorization Server as the `issuer_state` parameter value.
+    * `authorization_server`: OPTIONAL string that the Wallet can use to identify the Authorization Server to use with this grant type when `authorization_servers` parameter in the Credential Issuer metadata has multiple entries. It MUST NOT be used otherwise. The value of this parameter MUST match with one of the values in the `authorization_servers` array obtained from the Credential Issuer metadata.
+  * `urn:ietf:params:oauth:grant-type:pre-authorized_code`: OPTIONAL. Object for the Pre-authorized Code Grant type.
+    * `pre-authorized_code`: REQUIRED. The code representing the Credential Issuer's authorization for the Wallet to obtain Credentials of a certain type. This code MUST be short lived and single use. If the Wallet decides to use the Pre-Authorized Code Flow, this parameter value MUST be included in the subsequent Token Request with the Pre-Authorized Code Flow.
+    * `tx_code`: OPTIONAL. Object indicating that a Transaction Code is required if present, even if empty. It describes the requirements for a Transaction Code, which the Authorization Server expects the End-User to present along with the Token Request in a Pre-Authorized Code Flow. If the Authorization Server does not expect a Transaction Code, this object is absent; this is the default. The Transaction Code is intended to bind the Pre-Authorized Code to a certain transaction to prevent replay of this code by an attacker that, for example, scanned the QR code while standing behind the legitimate End-User. It is RECOMMENDED to send the Transaction Code via a separate channel. If the Wallet decides to use the Pre-Authorized Code Flow, the Transaction Code value MUST be sent in the `tx_code` parameter with the respective Token Request as defined in (#token-request). If no `length`, `description`, or `input_mode` is given, this object MAY be empty.
+      * `input_mode` : OPTIONAL. String specifying the input character set. Possible values are `numeric` (only digits) and `text` (any characters). The default is `numeric`.
+      * `length`: OPTIONAL. Integer specifying the length of the Transaction Code. This helps the Wallet to render the input screen and improve the user experience.
+      * `description`: OPTIONAL. String containing guidance for the Holder of the Wallet on how to obtain the Transaction Code, e.g., describing over which communication channel it is delivered. The Wallet is RECOMMENDED to display this description next to the Transaction Code input screen to improve the user experience. The length of the string MUST NOT exceed 300 characters. The `description` does not support internationalization, however the Issuer MAY detect the Holder's language by previous communication or an HTTP Accept-Language header within an HTTP GET request for a Credential Offer URI.
+    * `authorization_server`: OPTIONAL string that the Wallet can use to identify the Authorization Server to use with this grant type when `authorization_servers` parameter in the Credential Issuer metadata has multiple entries. It MUST NOT be used otherwise. The value of this parameter MUST match with one of the values in the `authorization_servers` array obtained from the Credential Issuer metadata.


for reviews: this part is only moved upwards

Co-authored-by: Gareth Oliver <gco@google.com>

paulbastian · 2026-07-02T15:44:33Z


 Additional Credential Offer parameters MAY be defined and used.
 The Wallet MUST ignore any unrecognized parameters.



these editorial changes move these two lines further down, which currently split the grants parameter from the grants values

Co-authored-by: Paul Bastian <paul.bastian@posteo.de>

Co-authored-by: Joseph Heenan <joseph@authlete.com>

paulbastian · 2026-07-30T14:28:43Z

@jogu could you review again please?
@fkj @c2bo can you review?

dpostnikov · 2026-08-05T08:40:54Z

DCP WG call today: Awaiting @jogu and @c2bo review

c2bo

Small nit/proposal and I am wondering if calling it redirect_uri which directly clashes with OAuth naming is helpful or harmful. Maybe we should call it something like issuer_return_uri instead?

Looks good to me otherwise.

jogu · 2026-09-17T14:47:59Z

Small nit/proposal and I am wondering if calling it redirect_uri which directly clashes with OAuth naming is helpful or harmful. Maybe we should call it something like issuer_return_uri instead?

I agree with Christian - I think using a different name would really help avoid confusing, having two redirect_uris (the oauth one and this new one) in the same flow sounds like something best avoided.

brentzundel · 2026-09-17T15:59:27Z

Discussed today, no opposition in group to the change suggested here: #759 (review)
@jogu will finish his review and @GarethCOliver will review

c2bo · 2026-09-17T16:36:09Z

I thought a bit about @jogu's comments during today's WG call. I believe the usual OAuth risk of redirec_uri don't really apply here since the redirect is not part of the security critical parts, but simply a redirect for information/UX - so at most a phishing angle still protected by TLS? I guess it would make sense nonetheless to warn to not use an origin that also hosts an open redirector etc.

Alternative solution: Rename the expected_redirect_origins parameter to something else and allow it to carry both, origins and URIs -> deployments can choose to use either an origin or full URLs. That gives deployments the freedom to adjust this to their deployment reality and should be reasonably easy to implement on the Wallet side: if the string contains path/query values, treat it as a strict URL match, otherwise compare prefix (origin).

jogu · 2026-09-17T14:52:10Z


+## Redirect to the Credential Issuer {#redirect-security}
+
+The `expected_redirect_origins` Credential Issuer metadata parameter allows the Wallet to authenticate the origin of the `redirect_uri`. An attacker that is able to modify a Credential Offer, as described in (#credential-offer-security), can therefore manipulate the path, query, and fragment components under a listed origin. Credential Issuers therefore SHOULD only list origins whose content they fully control. In multi-tenant environments, this is achieved by hosting each tenant on its own subdomain, so that every tenant has a distinct origin, and by listing only that tenant's origin in `expected_redirect_origins`. Credential Issuers that cannot separate origins in this way and that are concerned about phishing attacks SHOULD NOT use the `redirect_uri` Credential Offer parameter.


This feels like we're still leaving a foot gun there - is there really a clear use case that means (for example) we couldn't like URLs and require everything except the url query to match?

Paul and I discussed a bit:

I understand his reason for using origins is that it can be troublesome to get paths in the .well-known updated when the expected redirect uris need to change.

I still think that allowing a redirect to anywhere opens the possibility for some phishing attacks - e.g. as an attack I send a credential offer issues a credential to the user, then redirects to somewhere on a massive website that ends up suggesting the user presents their new credential to an attacker controlled site to "prove your credential works" or "see how the flow works".

It feels to me like the same set of people that have trouble updating origins in .well-known has some overlap with the set of people that will have huge websites where that potential for user generated content is there.

It's definitely a trade off. I think I'm still feeling like the better option is to force the security on people, meaning they end up having to either get the .well-known updated, or spin up a subdomain (the latter being what we're basically recommending anyway). My fear is without that people will cut corners ("it's only a should, we can ignore it as it's difficult for us").

jogu · 2026-09-17T14:56:14Z

+## Redirect to the Credential Issuer {#redirect-security}
+
+The `expected_redirect_origins` Credential Issuer metadata parameter allows the Wallet to authenticate the origin of the `redirect_uri`. An attacker that is able to modify a Credential Offer, as described in (#credential-offer-security), can therefore manipulate the path, query, and fragment components under a listed origin. Credential Issuers therefore SHOULD only list origins whose content they fully control. In multi-tenant environments, this is achieved by hosting each tenant on its own subdomain, so that every tenant has a distinct origin, and by listing only that tenant's origin in `expected_redirect_origins`. Credential Issuers that cannot separate origins in this way and that are concerned about phishing attacks SHOULD NOT use the `redirect_uri` Credential Offer parameter.
+


I think we should add to the text in privacy considerations to, not disimmilar to the text we already have about the oauth redirect url.

I don't understand this

jogu · 2026-09-17T16:41:47Z

 * `nonce_endpoint`: OPTIONAL. URL of the Credential Issuer's Nonce Endpoint, as defined in (#nonce-endpoint). This URL MUST use the `https` scheme and MAY contain port, path, and query parameter components. If omitted, the Credential Issuer does not require the use of `c_nonce`.
 * `deferred_credential_endpoint`: OPTIONAL. URL of the Credential Issuer's Deferred Credential Endpoint, as defined in (#deferred-credential-issuance). This URL MUST use the `https` scheme and MAY contain port, path, and query parameter components. If omitted, the Credential Issuer does not support the Deferred Credential Endpoint.
 * `notification_endpoint`: OPTIONAL. URL of the Credential Issuer's Notification Endpoint, as defined in (#notification-endpoint). This URL MUST use the `https` scheme and MAY contain port, path, and query parameter components. If omitted, the Credential Issuer does not support the Notification Endpoint.
+* `expected_redirect_origins`: REQUIRED if the Credential Issuer uses the `redirect_uri` Credential Offer parameter (#credential-offer-parameters), and otherwise omitted. A non-empty array of strings, where each string is an origin, as defined in [@!RFC6454], that the Credential Issuer may use in the `redirect_uri` of the Credential Offer. If a Credential Offer contains a `redirect_uri`, the Wallet MUST NOT utilize it unless the origin of the `redirect_uri` matches one of the values in this array. If this parameter is omitted, the Wallet MUST ignore any `redirect_uri` present in a Credential Offer from this Credential Issuer.


The 'MUST NOT utilize' here duplicates the MUST in the parameter definition:

Because the Credential Offer is not authenticated (see (#credential-offer-security)), the Wallet MUST validate this value against the expected_redirect_origins Credential Issuer metadata parameter as defined in (#credential-issuer-parameters) and MUST ignore the redirect_uri if the validation fails.

I'd suggest removing the MUST here and referring to the normative text in the parameter definition.

I think we have similar duplications of MUST statements throughout the spec, I don't see a concern here

brentzundel · 2026-09-24T15:18:03Z

Discussed in meeting, @paulbastian will address open comments

Co-authored-by: Joseph Heenan <joseph@authlete.com>

add redirect_uri to Credential Offer

9677a51

dpostnikov requested review from GarethCOliver and fkj June 22, 2026 08:06

paulbastian commented Jun 22, 2026

View reviewed changes

Comment thread 1.1/openid-4-verifiable-credential-issuance-1_1.md Outdated

Apply suggestion from wg discussion

e127cca

paulbastian commented Jun 22, 2026

View reviewed changes

GarethCOliver reviewed Jun 22, 2026

View reviewed changes

brentzundel mentioned this pull request Jun 25, 2026

Add redirect_uri to (Deferred) Credential (Error) Response to continue interaction with end user #723

Closed

fkj reviewed Jun 29, 2026

View reviewed changes

Comment thread 1.1/openid-4-verifiable-credential-issuance-1_1.md Outdated

Comment thread 1.1/openid-4-verifiable-credential-issuance-1_1.md Outdated

paulbastian and others added 4 commits July 1, 2026 10:05

Apply suggestions from code review

293a9a6

Co-authored-by: Gareth Oliver <gco@google.com>

Apply suggestion from @paulbastian

756809a

Merge branch 'main' into pb/redirect

636ee78

Fix Credential Offer parameter description

92842de

paulbastian mentioned this pull request Jul 1, 2026

Warm welcome URL et al #773

Open

paulbastian commented Jul 2, 2026

View reviewed changes

GarethCOliver approved these changes Jul 9, 2026

View reviewed changes

mickrau approved these changes Jul 9, 2026

View reviewed changes

jogu requested changes Jul 15, 2026

View reviewed changes

c2bo reviewed Jul 16, 2026

View reviewed changes

Comment thread 1.0/openid-4-verifiable-credential-issuance-1_0.md

paulbastian commented Jul 16, 2026

View reviewed changes

Comment thread 1.1/openid-4-verifiable-credential-issuance-1_1.md Outdated

paulbastian and others added 2 commits July 16, 2026 17:13

Apply suggestions from code review

86ecefe

Co-authored-by: Paul Bastian <paul.bastian@posteo.de>

Apply suggestion from @jogu

d5875ce

Co-authored-by: Joseph Heenan <joseph@authlete.com>

paulbastian commented Jul 16, 2026

View reviewed changes

Comment thread 1.1/openid-4-verifiable-credential-issuance-1_1.md Outdated

Apply suggestion from @paulbastian

9cc226e

paulbastian commented Jul 21, 2026

View reviewed changes

Comment thread 1.1/openid-4-verifiable-credential-issuance-1_1.md Outdated

paulbastian added 2 commits July 21, 2026 14:58

Apply suggestion from @paulbastian

1cd33ec

rename expected_redirect_origin to expected_redirect_origins

9bf2345

paulbastian commented Jul 21, 2026

View reviewed changes

Comment thread 1.1/openid-4-verifiable-credential-issuance-1_1.md Outdated

paulbastian added 2 commits July 21, 2026 19:09

Apply suggestion from @paulbastian

b1fee80

remove issuer_state parameter from redirect_uri

415c797

paulbastian added 3 commits July 30, 2026 16:24

minor fixes

d14ad13

add security consideration for redirect_uri

765bf58

clarification on which user agent is used on redirect_uri

cee9e79

Sakurann requested review from c2bo, fkj and jogu July 30, 2026 15:49

fkj approved these changes Jul 30, 2026

View reviewed changes

c2bo approved these changes Aug 31, 2026

View reviewed changes

Comment thread 1.1/openid-4-verifiable-credential-issuance-1_1.md Outdated

jogu reviewed Sep 17, 2026

View reviewed changes

paulbastian and others added 7 commits September 30, 2026 09:12

Update 1.1/openid-4-verifiable-credential-issuance-1_1.md

8f64541

Co-authored-by: Joseph Heenan <joseph@authlete.com>

renaming redirect_uri to issuer_redirect_uri

b1f366e

adding issuer_redirect_uri to example

c670641

add security consideration

709bf41

nit by Joseph

9c7f9b7

clarify to use comparison rules also from RFC6454

7764928

Merge branch 'main' into pb/redirect

58daf00


		Additional Credential Offer parameters MAY be defined and used.
		The Wallet MUST ignore any unrecognized parameters.


		## Redirect to the Credential Issuer {#redirect-security}

		The `expected_redirect_origins` Credential Issuer metadata parameter allows the Wallet to authenticate the origin of the `redirect_uri`. An attacker that is able to modify a Credential Offer, as described in (#credential-offer-security), can therefore manipulate the path, query, and fragment components under a listed origin. Credential Issuers therefore SHOULD only list origins whose content they fully control. In multi-tenant environments, this is achieved by hosting each tenant on its own subdomain, so that every tenant has a distinct origin, and by listing only that tenant's origin in `expected_redirect_origins`. Credential Issuers that cannot separate origins in this way and that are concerned about phishing attacks SHOULD NOT use the `redirect_uri` Credential Offer parameter.

Conversation

paulbastian commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

paulbastian commented Jul 30, 2026

Uh oh!

dpostnikov commented Aug 5, 2026

Uh oh!

c2bo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jogu commented Sep 17, 2026

Uh oh!

brentzundel commented Sep 17, 2026

Uh oh!

c2bo commented Sep 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

brentzundel commented Sep 24, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

paulbastian commented Jun 18, 2026 •

edited

Loading