openid
Confusion about the origin of the 'aud' value in the stream configuration
While on the Conformance Test Suite conference call, it became clear that there is some confusion around the origin of where the receivers aud value comes from.
While the spec says:
aud
Transmitter-Supplied, REQUIRED. A string or an array of strings containing an audience claim as defined in JSON Web Token (JWT)[RFC7519] that identifies the Event Receiver(s) for the Event Stream. This property cannot be updated. If multiple Receivers are specified then the Transmitter SHOULD know that these Receivers are the same entity.
The "transmitter-supplied", while correct in the sense this is a response object from the transmitter, is causing confusing that the transmitter is expected to "just know" this value. However this is really part of the "Receiver Configuration" which is NOT IN SPEC.
Basically there exists some flow before the spec that associates a receiver to a transmitter, during this time the receiver would share the audience it wants to set, and would get back a Bearer token to be used for all proceeding calls.
This should be noted in the description that this is a "pre-established" field while associating a receiver and transmitter.
┌─────────────────┐ /reg?aud="https://example.com"┌─────────────────┐
│ ┼────────────────────────────────►│ │
│ │ │ │
│ Receiver │ Register Receiver │ Transmitter │
│ │ │ │
│ │ │ │
│ │◄────────────────────────────────┼ │
│ │ id=123, token="eyBQe..." │ │
│ │ │ │
└─────────────────┘ └─────────────────┘
┌─────────────────┐ /stream {Bearer eyBQe..."} ┌─────────────────┐
│ ┼────────────────────────────────►│ │
│ │ │ │
│ Receiver │ Create New Stream │ Transmitter │
│ │ │ │
│ │ │ │
│ │◄────────────────────────────────┼ │
│ │ {"stream_id":"XYZ", ...} │ │
│ │ │ │
└─────────────────┘ └─────────────────┘
See this comment on a different issue: https://github.com/openid/sharedsignals/issues/207#issuecomment-2613004060
I have now seen three possibilities for defining the aud value in implementations. We should decide which of these is the "correct" way to do things so that Transmitters and Receivers can all build with the same expectations.
- ReceiverCompany says, "My aud value is www.receivercompany.com". They set up an agreement with TransmitterCompany so that any streams set up between the two companies use "www.receivercompany.com" as the aud value. The auth provided during stream creation allows the Transmitter to check that the Receiver is coming from ReceiverCompany and it is safe to send that aud value.
- ReceiverCompany says, "My aud value is www.receivercompany.com". TransmitterCompany offers a UI that allows an admin to create a stream with any company. In the UI, the admin is asked to plug in the aud value. For streams that the admin creates with ReceiverCompany, they plug in "www.receivercompany.com" as the aud value. The auth provided during stream creation allows the Transmitter to check that the Receiver is coming from ReceiverCompany and it is safe to send that aud value.
- When TransmitterCompany creates a stream, they generate a unique aud value for the stream without regard for what company runs the Receiver. The auth provided during stream creation ensures that this is safe and uniquely identifies a Receiver.