Skip to content

Commit a7272ae

Browse files
tulshitulshi
authored
Fixes #60 - are subjecst required (#70)
* Fixes #60 - are subjecst required * Incorporated Shayne's feedback * removed special case for single-stream transmitters
1 parent c5e093b commit a7272ae

File tree

3 files changed

+277
-115
lines changed

3 files changed

+277
-115
lines changed

‎openid-sharedsignals-framework-1_0.html‎

Lines changed: 81 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3709,14 +3709,28 @@ <h5 id="name-verification-event">
37093709
triggered. This is a nested attribute in the event payload.<a href="#section-7.1.4.1-5.1.1" class="pilcrow"></a></p>
37103710
</li>
37113711
</ul>
3712-
<p id="section-7.1.4.1-6">Upon receiving a Verification Event, the Event Receiver SHALL parse the SET and
3712+
<p id="section-7.1.4.1-6">subject<a href="#section-7.1.4.1-6" class="pilcrow"></a></p>
3713+
<ul class="normal ulEmpty">
3714+
<li class="normal ulEmpty" id="section-7.1.4.1-7.1">
3715+
<p id="section-7.1.4.1-7.1.1">REQUIRED. The value of the <code>subject</code> field in a Verification Event MUST always
3716+
be set to have a simple value of type <code>opaque</code>. The <code>id</code> of the value MUST be
3717+
the <code>stream_id</code> of the stream being verified.<a href="#section-7.1.4.1-7.1.1" class="pilcrow"></a></p>
3718+
</li>
3719+
</ul>
3720+
<ul class="normal ulEmpty">
3721+
<li class="normal ulEmpty" id="section-7.1.4.1-8.1">
3722+
<p id="section-7.1.4.1-8.1.1">Note that the subject that identifies a stream itself is always implicitly
3723+
added to the stream and MAY NOT be removed from the stream.<a href="#section-7.1.4.1-8.1.1" class="pilcrow"></a></p>
3724+
</li>
3725+
</ul>
3726+
<p id="section-7.1.4.1-9">Upon receiving a Verification Event, the Event Receiver SHALL parse the SET and
37133727
validate its claims. In particular, the Event Receiver SHALL confirm that the
37143728
value for "state" is as expected. If the value of "state" does not match, an
37153729
error response of "setData" SHOULD be returned (see Section 2.3 of
3716-
<span>[<a href="#DELIVERYPUSH" class="cite xref">DELIVERYPUSH</a>]</span> or <span>[<a href="#DELIVERYPOLL" class="cite xref">DELIVERYPOLL</a>]</span>).<a href="#section-7.1.4.1-6" class="pilcrow"></a></p>
3717-
<p id="section-7.1.4.1-7">In many cases, Event Transmitters MAY disable or suspend an Event Stream that
3730+
<span>[<a href="#DELIVERYPUSH" class="cite xref">DELIVERYPUSH</a>]</span> or <span>[<a href="#DELIVERYPOLL" class="cite xref">DELIVERYPOLL</a>]</span>).<a href="#section-7.1.4.1-9" class="pilcrow"></a></p>
3731+
<p id="section-7.1.4.1-10">In many cases, Event Transmitters MAY disable or suspend an Event Stream that
37183732
fails to successfully verify based on the acknowledgement or lack of
3719-
acknowledgement by the Event Receiver.<a href="#section-7.1.4.1-7" class="pilcrow"></a></p>
3733+
acknowledgement by the Event Receiver.<a href="#section-7.1.4.1-10" class="pilcrow"></a></p>
37203734
</section>
37213735
</div>
37223736
<div id="triggering-a-verification-event">
@@ -3833,6 +3847,10 @@ <h5 id="name-triggering-a-verification-e">
38333847
"iat": 1493856000,
38343848
"events": {
38353849
"https://schemas.openid.net/secevent/ssf/event-type/verification":{
3850+
"subject": {
3851+
"format": "opaque",
3852+
"id": "f67e39a0a4d34d56b3aa1bc4cff0069f"
3853+
},
38363854
"state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
38373855
}
38383856
}
@@ -3881,14 +3899,27 @@ <h4 id="name-stream-updated-event">
38813899
<p id="section-7.1.5-9">subject<a href="#section-7.1.5-9" class="pilcrow"></a></p>
38823900
<ul class="normal ulEmpty">
38833901
<li class="normal ulEmpty" id="section-7.1.5-10.1">
3884-
<p id="section-7.1.5-10.1.1">OPTIONAL. Specifies the Subject Principal for whom the status has been updated.
3885-
If this claim is not included, then the status change was applied to all
3886-
subjects in the stream.<a href="#section-7.1.5-10.1.1" class="pilcrow"></a></p>
3902+
<p id="section-7.1.5-10.1.1">REQUIRED. Specifies the Subject Principal for whom the status has been updated.
3903+
If the event applies to the entire stream, the value of the <code>subject</code> field
3904+
MUST be of format <code>opaque</code>, and its <code>id</code> value MUST be the unique ID of the
3905+
stream.<a href="#section-7.1.5-10.1.1" class="pilcrow"></a></p>
3906+
</li>
3907+
</ul>
3908+
<ul class="normal ulEmpty">
3909+
<li class="normal ulEmpty" id="section-7.1.5-11.1">
3910+
<p id="section-7.1.5-11.1.1">Note that the subject that identifies a stream itself is always implicitly
3911+
added to the stream and MAY NOT be removed from the stream.<a href="#section-7.1.5-11.1.1" class="pilcrow"></a></p>
3912+
</li>
3913+
</ul>
3914+
<ul class="normal ulEmpty">
3915+
<li class="normal ulEmpty" id="section-7.1.5-12.1">
3916+
<p id="section-7.1.5-12.1.1">Below is a non-normative example of a <code>stream-updated</code> event with a specific
3917+
subject.<a href="#section-7.1.5-12.1.1" class="pilcrow"></a></p>
38873918
</li>
38883919
</ul>
3889-
<span id="name-example-stream-updated-set"></span><div id="figstreamupdatedset">
3920+
<span id="name-example-stream-updated-set-"></span><div id="figstreamupdatedset">
38903921
<figure id="figure-41">
3891-
<div class="lang-json sourcecode" id="section-7.1.5-11.1">
3922+
<div class="lang-json sourcecode" id="section-7.1.5-13.1">
38923923
<pre>
38933924
{
38943925
"jti": "123456",
@@ -3913,7 +3944,39 @@ <h4 id="name-stream-updated-event">
39133944
</pre>
39143945
</div>
39153946
<figcaption><a href="#figure-41" class="selfRef">Figure 41</a>:
3916-
<a href="#name-example-stream-updated-set" class="selfRef">Example: Stream Updated SET</a>
3947+
<a href="#name-example-stream-updated-set-" class="selfRef">Example: Stream Updated SET with tenant principal</a>
3948+
</figcaption></figure>
3949+
</div>
3950+
<ul class="normal ulEmpty">
3951+
<li class="normal ulEmpty" id="section-7.1.5-14.1">
3952+
<p id="section-7.1.5-14.1.1">Below is a non-normative example of a <code>stream-updated</code> event with a stream
3953+
subject.<a href="#section-7.1.5-14.1.1" class="pilcrow"></a></p>
3954+
</li>
3955+
</ul>
3956+
<span id="name-example-stream-updated-set-w"></span><div id="figstreamupdatedstreamset">
3957+
<figure id="figure-42">
3958+
<div class="lang-json sourcecode" id="section-7.1.5-15.1">
3959+
<pre>
3960+
{
3961+
"jti": "123456",
3962+
"iss": "https://transmitter.example.com",
3963+
"aud": "receiver.example.com",
3964+
"iat": 1493856000,
3965+
"events": {
3966+
"https://schemas.openid.net/secevent/ssf/event-type/stream-updated": {
3967+
"subject": {
3968+
"format": "opaque",
3969+
"id" : "f67e39a0a4d34d56b3aa1bc4cff0069f"
3970+
},
3971+
"status": "paused",
3972+
"reason": "Internal error"
3973+
}
3974+
}
3975+
}
3976+
</pre>
3977+
</div>
3978+
<figcaption><a href="#figure-42" class="selfRef">Figure 42</a>:
3979+
<a href="#name-example-stream-updated-set-w" class="selfRef">Example: Stream Updated SET with stream as the subject of single-stream Transmitter</a>
39173980
</figcaption></figure>
39183981
</div>
39193982
</section>
@@ -4116,7 +4179,7 @@ <h4 id="name-ssf-event-properties">
41164179
<p id="section-11.1.3-1">The SSF event MAY contain additional claims within the event payload that are
41174180
specific to the event type.<a href="#section-11.1.3-1" class="pilcrow"></a></p>
41184181
<span id="name-example-set-containing-a-ri"></span><div id="risc-event-subject-example">
4119-
<figure id="figure-42">
4182+
<figure id="figure-43">
41204183
<div class="lang-json sourcecode" id="section-11.1.3-2.1">
41214184
<pre>
41224185
{
@@ -4137,12 +4200,12 @@ <h4 id="name-ssf-event-properties">
41374200
}
41384201
</pre>
41394202
</div>
4140-
<figcaption><a href="#figure-42" class="selfRef">Figure 42</a>:
4203+
<figcaption><a href="#figure-43" class="selfRef">Figure 43</a>:
41414204
<a href="#name-example-set-containing-a-ri" class="selfRef">Example: SET Containing a RISC Event with a Phone Number Subject</a>
41424205
</figcaption></figure>
41434206
</div>
41444207
<span id="name-example-set-containing-a-ca"></span><div id="caep-event-properties-example">
4145-
<figure id="figure-43">
4208+
<figure id="figure-44">
41464209
<div class="lang-json sourcecode" id="section-11.1.3-3.1">
41474210
<pre>
41484211
{
@@ -4162,7 +4225,7 @@ <h4 id="name-ssf-event-properties">
41624225
}
41634226
</pre>
41644227
</div>
4165-
<figcaption><a href="#figure-43" class="selfRef">Figure 43</a>:
4228+
<figcaption><a href="#figure-44" class="selfRef">Figure 44</a>:
41664229
<a href="#name-example-set-containing-a-ca" class="selfRef">Example: SET Containing a CAEP Event with Properties</a>
41674230
</figcaption></figure>
41684231
</div>
@@ -4175,7 +4238,7 @@ <h4 id="name-explicit-typing-of-sets">
41754238
</h4>
41764239
<p id="section-11.1.4-1">SSF events MUST use explicit typing as defined in Section 2.3 of <span>[<a href="#RFC8417" class="cite xref">RFC8417</a>]</span>.<a href="#section-11.1.4-1" class="pilcrow"></a></p>
41774240
<span id="name-explicitly-typed-jose-heade"></span><div id="explicit-type-header">
4178-
<figure id="figure-44">
4241+
<figure id="figure-45">
41794242
<div class="lang-json sourcecode" id="section-11.1.4-2.1">
41804243
<pre>
41814244
{
@@ -4184,7 +4247,7 @@ <h4 id="name-explicit-typing-of-sets">
41844247
}
41854248
</pre>
41864249
</div>
4187-
<figcaption><a href="#figure-44" class="selfRef">Figure 44</a>:
4250+
<figcaption><a href="#figure-45" class="selfRef">Figure 45</a>:
41884251
<a href="#name-explicitly-typed-jose-heade" class="selfRef">Explicitly Typed JOSE Header</a>
41894252
</figcaption></figure>
41904253
</div>
@@ -4223,7 +4286,7 @@ <h4 id="name-the-aud-claim">
42234286
this service might reroute SETs to respective Receivers, an "aud" claim with
42244287
multiple Receivers would lead to unintended data disclosure.<a href="#section-11.1.6-3" class="pilcrow"></a></p>
42254288
<span id="name-example-set-with-array-aud-"></span><div id="figarrayaud">
4226-
<figure id="figure-45">
4289+
<figure id="figure-46">
42274290
<div class="lang-json sourcecode" id="section-11.1.6-4.1">
42284291
<pre>
42294292
{
@@ -4239,7 +4302,7 @@ <h4 id="name-the-aud-claim">
42394302
}
42404303
</pre>
42414304
</div>
4242-
<figcaption><a href="#figure-45" class="selfRef">Figure 45</a>:
4305+
<figcaption><a href="#figure-46" class="selfRef">Figure 46</a>:
42434306
<a href="#name-example-set-with-array-aud-" class="selfRef">Example: SET with array 'aud' claim</a>
42444307
</figcaption></figure>
42454308
</div>

‎openid-sharedsignals-framework-1_0.md‎

Lines changed: 47 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1732,6 +1732,15 @@ state
17321732
> OPTIONAL An opaque value provided by the Event Receiver when the event is
17331733
triggered. This is a nested attribute in the event payload.
17341734

1735+
subject
1736+
1737+
> REQUIRED. The value of the `subject` field in a Verification Event MUST always
1738+
be set to have a simple value of type `opaque`. The `id` of the value MUST be
1739+
the `stream_id` of the stream being verified.
1740+
1741+
> Note that the subject that identifies a stream itself is always implicitly
1742+
added to the stream and MAY NOT be removed from the stream.
1743+
17351744
Upon receiving a Verification Event, the Event Receiver SHALL parse the SET and
17361745
validate its claims. In particular, the Event Receiver SHALL confirm that the
17371746
value for "state" is as expected. If the value of "state" does not match, an
@@ -1816,6 +1825,10 @@ Event Receiver as a result of the above request:
18161825
"iat": 1493856000,
18171826
"events": {
18181827
"https://schemas.openid.net/secevent/ssf/event-type/verification":{
1828+
"subject": {
1829+
"format": "opaque",
1830+
"id": "f67e39a0a4d34d56b3aa1bc4cff0069f"
1831+
},
18191832
"state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
18201833
}
18211834
}
@@ -1852,9 +1865,16 @@ reason
18521865

18531866
subject
18541867

1855-
> OPTIONAL. Specifies the Subject Principal for whom the status has been updated.
1856-
If this claim is not included, then the status change was applied to all
1857-
subjects in the stream.
1868+
> REQUIRED. Specifies the Subject Principal for whom the status has been updated.
1869+
If the event applies to the entire stream, the value of the `subject` field
1870+
MUST be of format `opaque`, and its `id` value MUST be the unique ID of the
1871+
stream.
1872+
1873+
> Note that the subject that identifies a stream itself is always implicitly
1874+
added to the stream and MAY NOT be removed from the stream.
1875+
1876+
> Below is a non-normative example of a `stream-updated` event with a specific
1877+
subject.
18581878

18591879
~~~ json
18601880
{
@@ -1878,7 +1898,30 @@ subject
18781898
}
18791899
}
18801900
~~~
1881-
{: title="Example: Stream Updated SET" #figstreamupdatedset}
1901+
{: title="Example: Stream Updated SET with tenant principal" #figstreamupdatedset}
1902+
1903+
> Below is a non-normative example of a `stream-updated` event with a stream
1904+
subject.
1905+
1906+
~~~ json
1907+
{
1908+
"jti": "123456",
1909+
"iss": "https://transmitter.example.com",
1910+
"aud": "receiver.example.com",
1911+
"iat": 1493856000,
1912+
"events": {
1913+
"https://schemas.openid.net/secevent/ssf/event-type/stream-updated": {
1914+
"subject": {
1915+
"format": "opaque",
1916+
"id" : "f67e39a0a4d34d56b3aa1bc4cff0069f"
1917+
},
1918+
"status": "paused",
1919+
"reason": "Internal error"
1920+
}
1921+
}
1922+
}
1923+
~~~
1924+
{: title="Example: Stream Updated SET with stream as the subject of single-stream Transmitter" #figstreamupdatedstreamset}
18821925

18831926
# Authorization {#management-api-auth}
18841927
HTTP API calls from a Receiver to a Transmitter SHOULD be authorized by

0 commit comments

Comments
 (0)