Improve authentication mechanism for subscription events by m-nahum · Pull Request #580 · camaraproject/Commonalities

m-nahum · 2026-01-23T23:50:06Z

What type of PR is this?

enhancement/feature

What this PR does / why we need it:

This PR proposes to improve the authentication mechanism for subscription events.

It proposes two sink credential types to cater for clients with different authentication and authorization capabilities :

Clients that don't have authorization server capabilities can use simple access tokens that expire with the subscription.
Clients that have authorization server capabilities can use full access token capabilities. The authentication information needed to acquire the access token is pre-shared between the parties. A new access token can be acquired if it expires, decoupling the duration of the subscription from the expiration of the token.

This PR also proposes to remove from the spec two sink credential types that are not required anymore.

Which issue(s) this PR fixes:

Fixes #461

Does this PR introduce a breaking change?

Yes
No

-REFRESHTOKEN credential type is removed. It was not allowed in the current version of the spec.

Special notes for reviewers:

Changelog input

 - Introduction of new credential type PRIVATE_KEY_JWT, which requires pre-shared authentication information between the parties (token endpoint, client ID and JWKS URI). 
 - Removed REFRESHTOKEN credential type, which is not supported

Additional documentation

This section can be blank.

docs

linux-foundation-easycla · 2026-01-23T23:50:13Z

The committers listed above are authorized under a signed CLA.

✅ login: m-nahum / name: m-nahum (756621c, 8b1a31a, 8e9fb9b)
✅ login: m-nahum / name: MarceloNahum (1755bea, 6a756bb, a053e32, c8812df)
✅ login: PedroDiez / name: Pedro Díez García (599e3f0)

rartych · 2026-01-24T20:07:04Z

@m-nahum The procedure for EasyCLA signing is explained in https://github.com/camaraproject/EasyCLA repo.
Please check the status of Corporate CLA within your organization and follow the process.

artifacts/camara-cloudevents/event-subscription-template.yaml

rartych · 2026-01-26T08:35:10Z

@m-nahum Thank you for the input.
I think all the legacy requirements related to ACCESSTOKEN flow should stay in place with mostly the additions related to PRIVATE_KEY_JWT flow.
Possible extensions:

as we have mermaid diagram illustrating both flows it can be added (in the annex of the Guide document)
we have https://github.com/camaraproject/Commonalities/blob/main/artifacts/notification-as-cloud-event.yaml - it is not normative but shows how notification receiver can be implemented, we can think about another one with o PRIVATE_KEY_JWT flow.

PedroDiez · 2026-01-27T15:10:48Z

Thanks for the input @m-nahum.

@jpengar and myself have been reviewed it.

The following comments reflect Telefónica’s initial review and feedback on the content of this Pull Request:

The PRIVATE_KEY_JWT flow should be included and properly described in the documentation introduced by this PR. As a baseline, you may reuse the flow described in Issue #461.
As discussed in previous meetings, the description should use terminology aligned with CAMARA definitions (e.g., API Consumer, API Provider, etc.). The ICM flow diagrams can be used as a reference(e.g. ICM JWT Bearer flow)
Please align the wording throughout the PR to consistently use API Consumer and API Provider. A specific inline comment has been added for this.
The clarification note added regarding the new PRIVATE_KEY_JWT credential applies to both implicit and explicit subscription models. This should be explicitly stated to avoid ambiguity:

Note: To use credentialType with value PRIVATE_KEY_JWT, the client and server shall share the authentication information required to request an access token. This includes a client ID, a token endpoint, and a JWK set.
The ACCESSTOKEN sinkCredentialType model must be preserved for backward compatibility. While some documentation sections may require review, the model itself should not be changed. Part of the text removed in this PR should be restored, as it still applies to the existing ACCESSTOKEN credential use case, which remains unchanged.
The new PRIVATE_KEY_JWT sinkCredentialType should also be defined as a bearer token. There are two possible approaches:
- Implicitly assume this, but clearly document it to avoid misunderstandings.
- Explicitly define it in the object schema (e.g., via an accessTokenType attribute) under the new credential type, for example:
```
type: object
properties:
  accessTokenType:
    description: REQUIRED. The type of the access token. See OAuth 2.0 (https://tools.ietf.org/html/rfc6749#section-7.1).
    type: string
    enum:
      - bearer
required:
  - accessTokenType 
```

artifacts/camara-cloudevents/event-subscription-template.feature

m-nahum · 2026-01-30T16:52:13Z

@PedroDiez and @jpengar, thank you for your comments.

Regarding:

The new PRIVATE_KEY_JWT sinkCredentialType should also be defined as a bearer token. There are two possible approaches:

Implicitly assume this, but clearly document it to avoid misunderstandings.

Explicitly define it in the object schema (e.g., via an accessTokenType attribute) under the new credential type, for example:
type: object
properties:
  accessTokenType:
    description: REQUIRED. The type of the access token. See OAuth 2.0 (https://tools.ietf.org/html/rfc6749#section-7.1).
    type: string
    enum:
      - bearer
required:
  - accessTokenType 

The token type will be included in the token response when the API Provider requests an access token from the API Consumer authorization server. There is no reason to limit the token type to Bearer in this specification.

PedroDiez · 2026-02-02T16:10:13Z

@PedroDiez and @jpengar, thank you for your comments.

Regarding:
The new PRIVATE_KEY_JWT sinkCredentialType should also be defined as a bearer token. There are two possible approaches:

Implicitly assume this, but clearly document it to avoid misunderstandings.

Explicitly define it in the object schema (e.g., via an accessTokenType attribute) under the new credential type, for example:
type: object
properties:
  accessTokenType:
    description: REQUIRED. The type of the access token. See OAuth 2.0 (https://tools.ietf.org/html/rfc6749#section-7.1).
    type: string
    enum:
      - bearer
required:
  - accessTokenType 
The token type will be included in the token response when the API Provider requests an access token from the API Consumer authorization server. There is no reason to limit the token type to Bearer in this specification.

Hi @m-nahum,

The point is that we want to keep both securitization approacahes in terms of behavior, so guaranteeing backwards compatibility. It was discussed in the past the use of "bearer" token. No matter to not explicitly indicate in subscription phase, but indicate that tokens issued are "bearer" token type.

documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md

rartych · 2026-02-03T12:38:45Z

documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md

+
+  opt Using ACCESSTOKEN sink credential type
+    opt Subscription
+      appbe ->> cspres: POST /subscription<br>Body: {<br>sink: <API Consumer>/notification,<br>sinkCredential:{ credentialType: ACCESSTOKEN,<br>accessToken:<Access Token>,<br>accessTokenExpireUtc:<access token expire time>,<br>accessTokenType: bearer },<br>...}


Suggested change

appbe ->> cspres: POST /subscription Body: { sink: <API Consumer>/notification, sinkCredential:{ credentialType: ACCESSTOKEN, accessToken:<Access Token>, accessTokenExpireUtc:<access token expire time>, accessTokenType: bearer }, ...}

appbe ->> cspres: POST /subscriptions Body: { sink: <API Consumer>/sink, sinkCredential:{ credentialType: ACCESSTOKEN, accessToken:<Access Token>, accessTokenExpireUtc:<access token expire time>, accessTokenType: bearer }, ...}

documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md

rartych · 2026-02-03T15:57:04Z

The definition of plain credentials in subscription template looks awkward:

PLAIN: "#/components/schemas/PlainCredential"
...
PlainCredential:
...

but it is intended for protocols with plain security (and is inherited from original CloudEvents subscription template).
Currently other protocols are not used, and this credential type is also excluded, but it is kept for future (and present in subscription APIs).
I think we should not remove it within this PR.
It can be separate issue to decide if such cleanup is needed.

Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com>

documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md

PedroDiez · 2026-02-04T13:19:36Z

documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md

    }
 }
 ```
+Note: To use `credentialType` with value `PRIVATE_KEY_JWT`, the API Consumer and API Provider shall share


I think this part it would be better below the above table for editorial aligment with Explicit Susbcription (after line 79)

Agree with Pedro

documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md

rartych · 2026-02-04T15:30:42Z

documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md

+  opt Using PRIVATE_KEY_JWT sink credential type
+    note over appclient,cspclient: Onboarding: <br> API Consumer shares <Token Endpoint> and <Client ID><br>API Provider shares <JWKS URI>
+    opt Subscription
+      appclient ->> cspres: POST /subscription<br>Body: {<br>sink: <API Consumer 2>/notification,<br>sinkCredential:{ credentialType: PRIVATE_KEY_JWT },<br>...}


Similar changes as for ACCESSTOKEN flow:

Suggested change

appclient ->> cspres: POST /subscription Body: { sink: <API Consumer 2>/notification, sinkCredential:{ credentialType: PRIVATE_KEY_JWT }, ...}

appclient ->> cspres: POST /subscriptions Body: { sink: <API Consumer 2>/sink, sinkCredential:{ credentialType: PRIVATE_KEY_JWT }, ...}

rartych · 2026-02-04T15:31:01Z

documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md

+    end
+
+    opt Notification
+      cspclient ->> appres: POST /notification<br>Authorization: Bearer <Access Token><br>Body: { ... }


Suggested change

cspclient ->> appres: POST /notification Authorization: Bearer <Access Token> Body: { ... }

cspclient ->> appres: POST /sink Authorization: Bearer <Access Token> Body: { ... }

rartych · 2026-02-04T15:55:34Z

Due to document structure we have twice the following stance:

... the API Consumer and API Provider shall share authentication information needed to request an access token. This includes a client ID, a token endpoint and a JWK set.

For security experts it is obvious what client ID and JWK set mean here, but I guess we can add some references or explanation for general public, for example:

The client ID uniquely identifies the application ([RFC 6749, Section 2.2](https://www.rfc-editor.org/rfc/rfc6749.html#section-2.2)), while the JWK Set ((JSON Web Key Set)) contains the cryptographic keys used for authentication ([RFC 7517](https://www.rfc-editor.org/rfc/rfc7517.html))

m-nahum · 2026-02-04T16:12:33Z

The definition of plain credentials in subscription template looks awkward:
PLAIN: "#/components/schemas/PlainCredential"
...
PlainCredential:
...
but it is intended for protocols with plain security (and is inherited from original CloudEvents subscription template). Currently other protocols are not used, and this credential type is also excluded, but it is kept for future (and present in subscription APIs). I think we should not remove it within this PR. It can be separate issue to decide if such cleanup is needed.

@rartych
Following the same logic, should I put back the REFRESHTOKEN credential definition as well ?

rartych · 2026-02-04T18:18:10Z

Following the same logic, should I put back the REFRESHTOKEN credential definition as well ?

My understanding is that we concluded that using REFRESHTOKEN is not feasible in CAMARA event notification, hence using pre-shared information as alternative solution is proposed.
We can decide in the future about further cleanup in the template or enabling protocols using plain credentials.

patrice-conil

LGTM after the modifications requested by Pedro and Rafal are implemented.

patrice-conil · 2026-02-05T12:38:29Z

documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md

    }
 }
 ```
+Note: To use `credentialType` with value `PRIVATE_KEY_JWT`, the API Consumer and API Provider shall share


Agree with Pedro

m-nahum · 2026-02-05T18:58:18Z

@rartych, @PedroDiez , @patrice-conil

Due to document structure we have twice the following stance:

... the API Consumer and API Provider shall share authentication information needed to request an access token. This includes a client ID, a token endpoint and a JWK set.

For security experts it is obvious what client ID and JWK set mean here, but I guess we can add some references or explanation for general public, for example:

The client ID uniquely identifies the application ([RFC 6749, Section 2.2](https://www.rfc-editor.org/rfc/rfc6749.html#section-2.2)), while the JWK Set ((JSON Web Key Set)) contains the cryptographic keys used for authentication ([RFC 7517](https://www.rfc-editor.org/rfc/rfc7517.html))

To avoid having the note in 2 places and add the additional references, I propose to add a section to the Security section that explains the pre-requisites for using PRIVATE_KEY_JWT

paths

PedroDiez

Editorial comment.

LGTM at functional level

artifacts/camara-cloudevents/event-subscription-template.yaml

artifacts/camara-cloudevents/event-subscription-template.feature

Co-authored-by: Pedro Díez García <pedro.diezgarcia@telefonica.com>

rartych

LGTM

Clarified description of ACCESS_TOKEN_EXPIRED reason. Aligned with CAMARA API Design Guide

PedroDiez

Minor point aligned in a commit

PedroDiez

LGTM

rartych

Reapproved.

patrice-conil

LGTM

Fixes for issue-461

c8812df

m-nahum requested review from PedroDiez, jlurien, patrice-conil, rartych and shilpa-padgaonkar as code owners January 23, 2026 23:50

rartych reviewed Jan 26, 2026

View reviewed changes

artifacts/camara-cloudevents/event-subscription-template.yaml Outdated Show resolved Hide resolved

PedroDiez reviewed Jan 27, 2026

View reviewed changes

artifacts/camara-cloudevents/event-subscription-template.feature Show resolved Hide resolved

Addressed PR comments

6a756bb

rartych mentioned this pull request Feb 2, 2026

Scope of the Spring release #543

Open