Support for advertising Transmitter metadata for multiple versions of spec

[cisco-skolla]

Current SSF transmitter metadata endpoint doesn't allow supporting multiple versions of the spec. Do you have any recommendations on supporting multiple versions?

If a transmitter wants to support multiple versions of the specification, transmitter has to maintain separate metadata endpoints for each version of the spec. Instead, if the metadata endpoint allows publishing the metadata per spec, that would avoid managing multiple sets of metadata endpoints. This will allow transmitters supporting multiple versions (v1, v2, v3..) of the spec and receivers can get the information just by invoking metadata endpoint .well-known/ssf-configuration without having human intervention.

Current Transmitter Configuration /.well-known/ssf-configuration response:

{
  "spec_version": "1_0-ID3",
  "issuer":
    "https://tr.example.com",
  "jwks_uri":
    "https://tr.example.com/jwks.json",
  "delivery_methods_supported": [
    "urn:ietf:rfc:8935",
    "urn:ietf:rfc:8936"],
  "events_supported": [
    "https://schemas.openid.net/secevent/ssf/event-type/stream-updated",
    "https://schemas.openid.net/secevent/ssf/event-type/verification",
    "https://schemas.openid.net/secevent/risc/event-type/sessions-revoked"
    "https://schemas.openid.net/secevent/caep/event-type/session-revoked"],
  "configuration_endpoint":
    "https://tr.example.com/ssf/mgmt/stream",
  "status_endpoint":
    "https://tr.example.com/ssf/mgmt/status",
  "add_subject_endpoint":
    "https://tr.example.com/ssf/mgmt/subject:add",
  "remove_subject_endpoint":
    "https://tr.example.com/ssf/mgmt/subject:remove",
  "verification_endpoint":
    "https://tr.example.com/ssf/mgmt/verification",
  "critical_subject_members": [ "tenant", "user" ],
  "authorization_schemes":[
      {
        "spec_urn": "urn:ietf:rfc:6749"
      },
      {
        "spec_urn": "urn:ietf:rfc:8705"
      }
    ],
  "default_subjects": "NONE"
}

Asking for support for multiple versions:

{
  "1_0-ID3":{
  "issuer":
    "https://tr.example.com",
  "jwks_uri":
    "https://tr.example.com/jwks.json",
  "delivery_methods_supported": [
    "urn:ietf:rfc:8935",
    "urn:ietf:rfc:8936"],
  "events_supported": [
    "https://schemas.openid.net/secevent/ssf/event-type/stream-updated",
    "https://schemas.openid.net/secevent/ssf/event-type/verification",
    "https://schemas.openid.net/secevent/risc/event-type/sessions-revoked"
    "https://schemas.openid.net/secevent/caep/event-type/session-revoked"],
  "configuration_endpoint":
    "https://tr.example.com/ssf/mgmt/stream",
  "status_endpoint":
    "https://tr.example.com/ssf/mgmt/status",
  "add_subject_endpoint":
    "https://tr.example.com/ssf/mgmt/subject:add",
  "remove_subject_endpoint":
    "https://tr.example.com/ssf/mgmt/subject:remove",
  "verification_endpoint":
    "https://tr.example.com/ssf/mgmt/verification",
  "critical_subject_members": [ "tenant", "user" ],
  "authorization_schemes":[
      {
        "spec_urn": "urn:ietf:rfc:6749"
      },
      {
        "spec_urn": "urn:ietf:rfc:8705"
      }
    ],
  "default_subjects": "NONE"
}
"1_0-ID1" : {
  "issuer":
    "https://tr.example.com",
  "jwks_uri":
    "https://tr.example.com/jwks.json",
  "delivery_methods_supported": [
    "https://schemas.openid.net/secevent/risc/delivery-method/push",
    "https://schemas.openid.net/secevent/risc/delivery-method/poll"],
  "configuration_endpoint":
    "https://tr.example.com/sse/mgmt/stream",
  "status_endpoint":
    "https://tr.example.com/sse/mgmt/status",
  "add_subject_endpoint":
    "https://tr.example.com/sse/mgmt/subject:add",
  "remove_subject_endpoint":
    "https://tr.example.com/sse/mgmt/subject:remove",
  "verification_endpoint":
    "https://tr.example.com/sse/mgmt/verification",
  "critical_subject_members": [ "tenant", "user" ]
}

}

[dhs-BI]

Interesting idea - it would certainly help for multi-tenant systems as they upgrade over time to ensure support for older receivers for a period of time during the transition.

[appsdesh]

This would change the API response from a JSON object to a list of objects, breaking backward compatibility, and should be avoided at this phase of the spec lifecycle.

We launched the ID1 transmitter and have seamlessly supported ID1, ID2, and ID3 without needing this, so I'm curious about the ask! The usual guidance for the new implementers is to use the latest version; what use cases are you thinking of?

[cisco-skolla]

We launched the ID1 transmitter and have seamlessly supported ID1, ID2, and ID3 without needing this, so I'm curious about the ask! The usual guidance for the new implementers is to use the latest version; what use cases are you thinking of?

ID1 transmitter configuration endpoint is completely different /.well-known/sse-configuration from later versions /.well-known/ssf-configuration . How were you able to support multiple versions at the same time? What is the metadata url and response for supporting multiple versions would look like?

This would change the API response from a JSON object to a list of objects, breaking backward compatibility, and should be avoided at this phase of the spec lifecycle.

The one I proposed would be JSON object not list.

[FragLegs]

Why not just offer different well-known endpoints (possibly with different issuers) for each version supported?

[cisco-skolla]

Why not just offer different well-known endpoints (possibly with different issuers) for each version supported?

My thought was proposing auto-discovery of endpoints for each version of the spec. If we want to use well-known endpoint per each version of the spec, the receiver has to find out that via out-of-band mechanism.

[appsdesh]

ID1 transmitter configuration endpoint is completely different /.well-known/sse-configuration from later versions /.well-known/ssf-configuration . How were you able to support multiple versions at the same time? What would the metadata URL and response for supporting multiple versions look like?

At this point, auto-discovery is not the goal, so receivers will need to know which URL to hit. Practically all new implementers should start with the latest versions.

The one I proposed would be JSON object not list.

That would still block existing receivers from processing this as data structure is different. So this is still backwards incompatible.

Other aspects were also discussed in the 3/18/2025 call

[cisco-skolla]

Thank you for the responses. Since auto-discovery is not the priority as discussed in the call, having different well-known endpoints (possibly with different issuers) for each version supported makes sense.