New optional callbackUrl request parameter

[jpengar]

What type of PR is this?

• enhancement/feature

What this PR does / why we need it:

This pull request enhances the consent API definition by introducing support for callback URLs during the consent capture flow, clarifying denial scenarios, and improving status handling. The changes add new functionality for redirecting users after consent actions and provide more explicit documentation and examples for denied consent cases.

Callback URL support and consent denial handling:

• Added support for an optional callbackUrl parameter in the consent capture request, allowing API Consumers to specify where the user should be redirected after completing the consent flow. Detailed documentation covers its behavior, security requirements, and possible outcome values in the callback.
• Included a new request example (ONE_SCOPE_CALLBACK_URL) demonstrating usage of the callbackUrl field in API requests.
• Added a new response example (CONSENT_DENIED) to illustrate how the API responds when consent is explicitly denied for a scope and purpose.
• UPDATE Extended test scenarios to cover callback URL behavior, including handling the state parameter and verifying correct redirection and result propagation.

UPDATE Status value improvements:

• Replaced the status value REVOKED with DENIED throughout the API, updating both the schema and the documentation to clarify that DENIED covers both explicit refusal and withdrawal of consent.

UPDATE Error Handling Improvements:

• Added error code (CONSENT_INFO.INVALID_CALLBACK_URL) and example for invalid callback URLs, ensuring that API Providers return a clear 403 error when the callback URL fails validation.
• Added a test scenario for invalid callback URL handling, verifying correct error response and messaging.

Which issue(s) this PR fixes:

Fixes #40

Special notes for reviewers:

N/A

Changelog input

new callbackUrl request parameter
new DENIED status

Additional documentation

N/A

[github-actions]

🦙 MegaLinter status: ✅ SUCCESS

Descriptor	Linter	Files	Fixed	Errors	Elapsed time
✅ ACTION	actionlint	2		0	0.01s
✅ API	spectral	1		0	1.48s
✅ GHERKIN	gherkin-lint	1		0	0.33s
✅ REPOSITORY	git_diff	yes		no	0.0s
✅ REPOSITORY	secretlint	yes		no	0.57s
✅ YAML	yamllint	1		0	0.42s

See detailed report in MegaLinter reports

MegaLinter is graciously provided by

[diegogonmar]

LGTM

[sebdewet]

LGTM

[AxelNennker]

My comment was not addressed.
#40 (comment)

The callback url must be preregistered and validated the same way as redirect_uri in authorization code flow.

This not about consent info replacing OIDC authorization code flow but about security.

[AxelNennker]

The API Consumer should not allow arbitrary callback url.

An attacker might succeed to insert its own callback url.

Should the PR contain a note to API consumers that the size of state should be limited - to say 2048 bytes - because browser impose length restrictions?

Should PR contain a note that the state should be opaque and MUST not contain visible PII?

[jpengar]

My comment was not addressed. #40 (comment)

The callback url must be preregistered and validated the same way as redirect_uri in authorization code flow.

This not about consent info replacing OIDC authorization code flow but about security.

The API Consumer should not allow arbitrary callback url.

An attacker might succeed to insert its own callback url.

Thanks for the feedback, @AxelNennker. We fully understand the reasoning behind the requirement for precise, pre-registered callback URIs, as implemented for redirect_uri in OIDC Authorization Code flows. This approach offers the strongest security.

However, two practical considerations lead us to recommend the current wording ('SHOULD') rather than a mandatory ('MUST') requirement in the API specification:

• Firstly, CAMARA relies on TMF-based onboarding processes, and there is currently no standard TMF mechanism to register callback/notification URIs for API Consumers. Mandating ('MUST') pre-registration would create a cross-vendor entry/adoption barrier until a TMF mechanism to register callback URLs is available. 'SHOULD' provides implementers with security guidance while avoiding a hard dependency on processes that are not yet available in the ecosystem (we are open to supporting a TMF change to add such a capability). NOTE: In the meantime, API Providers may require API Consumers to use non-TMF standard procedures to register callback URLs.
• Consent Info API endpoint is not an open, unauthenticated /authorize endpoint. Invocation requires valid client credentials. If an attacker already has those credentials, the presence or absence of a pre-registered callback URL does not materially increase their ability to cause harm. The core breach is credential compromise, not callback selection. The callback here is used for redirection after consent rather than transporting an authorization code or tokens directly.

Additionally, the CAMARA Commonalities (the Event Subscription and Notification Guide) already recommend that Event Producers may require pre-registration of notification URLs as part of their internal security measures. However, this is done in a flexible way that leaves enforcement to Providers' onboarding processes. Using the same 'SHOULD/Provider choice' model here maintains consistency across CAMARA APIs, and aligns with Commonalities security recommendations for notification endpoints with similar requirements.

Event Producers SHALL choose based on their internal security guidelines to implement measures based on the above guidance to ensure abuse protection. For e.g., An event producer might ask the subscriber to pre-register the notification URL at the time of app onboarding. If this registered notification URL doesn't match later with the notification URL in the request, the event producer can choose to reject the request with the relevant error code.

[jpengar]

Should the PR contain a note to API consumers that the size of state should be limited - to say 2048 bytes - because browser impose length restrictions?

@AxelNennker To be honest, I don't have a strong opinion on this one. I'm happy with it as it is.

[jpengar]

Should PR contain a note that the state should be opaque and MUST not contain visible PII?

@AxelNennker We can add it if you think it needs to be explicitly clarified. Do you want me to do so?

[diegogonmar]

LGTM

[jpengar]

As discussed in today's ICM meeting https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/357597203/2025-11-19+Draft+Agenda+ICM+Minutes, the group agreed to set a deadline to make a final decision on this topic at the next ICM meeting (Wednesday, December 3). This PR has been around for several weeks already, and the goal is to close it before the Christmas break.

[jpengar]

As discussed in today's ICM meeting https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/357597203/2025-11-19+Draft+Agenda+ICM+Minutes, the group agreed to set a deadline to make a final decision on this topic at the next ICM meeting (Wednesday, December 3). This PR has been around for several weeks already, and the goal is to close it before the Christmas break.

@AxelNennker @sebdewet A kind reminder to take a look at the discussion above regarding security restrictions for the callback URL. We should make a decision by next Wednesday. Thanks.

[sebdewet]

LGTM