Skip to content

Commit ba5ea39

Browse files
tulshitulshi
committed
Merge branch 'main' into mandatory-events
2 parents e2c1452 + 6ed4115 commit ba5ea39

File tree

1 file changed

+103
-41
lines changed

1 file changed

+103
-41
lines changed

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

Lines changed: 103 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -146,16 +146,42 @@ normative:
146146
date: May 2021
147147
target: https://datatracker.ietf.org/doc/html/draft-ietf-secevent-subject-identifiers
148148
title: Subject Identifiers for Security Event Tokens
149-
150-
informative:
151149
CAEP:
152150
author:
153-
- ins: A. Tulshibagwale
151+
-
152+
ins: T. Cappalli
153+
name: Tim Cappalli
154+
-
155+
ins: A. Tulshibagwale
156+
name: Atul Tulshibagwale
157+
date: August 2021
158+
target: https://openid.net/specs/openid-caep-specification-1_0.html
159+
title: OpenID Continuous Access Evaluation Profile 1.0 - draft 02
160+
RISC:
161+
author:
162+
-
163+
ins: M. Scurtescu
164+
name: Marius Scurtescu
165+
-
166+
ins: A. Backman
167+
name: Annabelle Backman
168+
-
169+
ins: P. Hunt
170+
name: Phil Hunt
171+
-
172+
ins: J. Bradley
173+
name: John Bradley
174+
-
175+
ins: S. Bounev
176+
name: Stan Bounev
177+
-
178+
ins: A. Tulshibagwale
154179
name: Atul Tulshibagwale
155-
org: Google
156-
date: February 2019
157-
target: https://cloud.google.com/blog/products/identity-security/re-thinking-federated-identity-with-the-continuous-access-evaluation-protocol
158-
title: ' Re-thinking Federated Identity with the Continuous Access Evaluation Protocol '
180+
date: April 2022
181+
target: https://openid.net/specs/openid-risc-profile-specification-1_0.html
182+
title: OpenID RISC Profile Specification 1.0 - draft 02
183+
184+
informative:
159185
USECASES:
160186
author:
161187
- ins: M. Scurtescu
@@ -217,10 +243,20 @@ Subject Principals are identified by Subject Members defined below.
217243

218244
# Subject Members in SSF Events {#subject-ids}
219245

220-
A member of type Subject in an SSF event MAY have any claim name. Each Subject Member MUST
221-
refer to exactly one Subject Principal.
246+
## Subject Members {#subject-members}
247+
A Subject Member of a SSF event describes a subject of the event. A top-level claim named `sub_id` MUST be used to describe the primary subject of the event.
222248

223-
A Subject may be a "simple subject" or a "complex subject".
249+
### Existing CAEP and RISC Events
250+
Event types already defined in the CAEP ({{CAEP}}) and RISC ({{RISC}}) specifications MAY use a `subject` field within the `events` claim of the SSF event to describe the primary Subject Principal of the event. SSF Transmitters MUST include the top-level `sub_id` claim even for these existing event types.
251+
252+
### New Event Types
253+
New event types MUST use the top-level `sub_id` claim and MUST NOT use the `subject` field in the `events` claim to describe the primary Subject Principal.
254+
255+
### Additional Subject Members
256+
Specific event types MAY define additional Subject Members if required to describe additional subjects of that event type (e.g. a Transferee). These additional subject fields MAY have any field name.
257+
258+
### Subject Member Values
259+
Each Subject Member MUST refer to exactly one Subject Principal. The value of a Subject Member MAY be a "simple subject" or a "complex subject".
224260

225261
## Simple Subject Members {#simple-subjects}
226262

@@ -230,7 +266,7 @@ Identifier" as defined in the Subject Identifiers for Security Event Tokens
230266
event.
231267

232268
~~~ json
233-
"transferer": {
269+
"sub_id": {
234270
"format": "email",
235271
"email": "foo@example.com"
236272
}
@@ -278,7 +314,7 @@ appear at most once in the Complex Subject value.
278314
Below is a non-normative example of a Complex Subject claim in a SSF event.
279315

280316
~~~ json
281-
"transferee": {
317+
"sub_id": {
282318
"format": "complex",
283319
"user" : {
284320
"format": "email",
@@ -406,6 +442,10 @@ The following are hypothetical examples of SETs that conform to the Shared Signa
406442
"jti": "756E69717565206964656E746966696572",
407443
"iat": 1520364019,
408444
"aud": "636C69656E745F6964",
445+
"sub_id": {
446+
"format": "email",
447+
"email": "foo@example.com"
448+
},
409449
"events": {
410450
"https://schemas.openid.net/secevent/risc/event-type/account-enabled": {
411451
"subject": {
@@ -424,6 +464,19 @@ The following are hypothetical examples of SETs that conform to the Shared Signa
424464
"jti": "756E69717565206964656E746966696572",
425465
"iat": 1520364019,
426466
"aud": "636C69656E745F6964",
467+
"sub_id": {
468+
"format": "complex",
469+
"user": {
470+
"format": "iss_sub",
471+
"iss": "https://idp.example.com/3957ea72-1b66-44d6-a044-d805712b9288/",
472+
"sub": "jane.smith@example.com"
473+
},
474+
"device": {
475+
"format": "iss_sub",
476+
"iss": "https://idp.example.com/3957ea72-1b66-44d6-a044-d805712b9288/",
477+
"sub": "e9297990-14d2-42ec-a4a9-4036db86509a"
478+
}
479+
},
427480
"events": {
428481
"https://schemas.openid.net/secevent/caep/event-type/session-revoked": {
429482
"subject": {
@@ -455,6 +508,10 @@ The following are hypothetical examples of SETs that conform to the Shared Signa
455508
"jti": "756E69717565206964656E746966696572",
456509
"iat": 1520364019,
457510
"aud": "636C69656E745F6964",
511+
"sub_id": {
512+
"format": "email",
513+
"email": "foo@example2.com"
514+
},
458515
"events": {
459516
"https://schemas.openid.net/secevent/caep/event-type/token-claims-change": {
460517
"subject": {
@@ -477,6 +534,10 @@ The following are hypothetical examples of SETs that conform to the Shared Signa
477534
"jti": "756E69717565206964656E746966696534",
478535
"iat": 15203800012,
479536
"aud": "636C69656E745F6324",
537+
"sub_id": {
538+
"format": "catalog_item",
539+
"catalog_id": "c0384/winter/2354122"
540+
},
480541
"events": {
481542
"https://schemas.openid.net/secevent/caep/event-type/token-claims-change": {
482543
"subject": {
@@ -1527,7 +1588,7 @@ Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
15271588
{
15281589
"stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
15291590
"status": "paused",
1530-
"reason": "Disabled by administrator action"
1591+
"reason": "Disabled by administrator action."
15311592
}
15321593
~~~
15331594
{: title="Example: Update Stream Status Request With Optional Reason" #figupdatestatuswithreasonreq}
@@ -1541,7 +1602,7 @@ Cache-Control: no-store
15411602

15421603
{
15431604
"stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
1544-
"status": "paused"
1605+
"status": "paused",
15451606
}
15461607
~~~
15471608
{: title="Example: Update Stream Status Response" #figupdatestatusresp}
@@ -1719,22 +1780,18 @@ A Transmitter MUST respond to verification event requests even if the event is n
17191780

17201781

17211782
#### Verification Event {#verification-event}
1722-
The Verification Event is a standard SET with the following attributes:
1723-
1724-
event type
1725-
1726-
> The Event Type URI is: "https://schemas.openid.net/secevent/ssf/event-type/verification".
1783+
The Verification Event is a SSF Event with the event type: "https://schemas.openid.net/secevent/ssf/event-type/verification". The event contains the following attribute:
17271784

17281785
state
17291786

17301787
> OPTIONAL An opaque value provided by the Event Receiver when the event is
1731-
triggered. This is a nested attribute in the event payload.
1788+
triggered.
1789+
1790+
As with any SSF event, the Verification Event has a top-level `sub_id` claim:
17321791

1733-
subject
1792+
sub_id
17341793

1735-
> REQUIRED. The value of the `subject` field in a Verification Event MUST always
1736-
be set to have a simple value of type `opaque`. The `id` of the value MUST be
1737-
the `stream_id` of the stream being verified.
1794+
> REQUIRED. The value of the top-level `sub_id` claim in a Verification Event MUST always be set to have a simple value of type `opaque`. The `id` of the value MUST be the `stream_id` of the stream being verified.
17381795

17391796
> Note that the subject that identifies a stream itself is always implicitly
17401797
added to the stream and MAY NOT be removed from the stream.
@@ -1821,12 +1878,12 @@ Event Receiver as a result of the above request:
18211878
"iss": "https://transmitter.example.com",
18221879
"aud": "receiver.example.com",
18231880
"iat": 1493856000,
1881+
"sub_id": {
1882+
"format": "opaque",
1883+
"id": "f67e39a0a4d34d56b3aa1bc4cff0069f"
1884+
},
18241885
"events": {
18251886
"https://schemas.openid.net/secevent/ssf/event-type/verification":{
1826-
"subject": {
1827-
"format": "opaque",
1828-
"id": "f67e39a0a4d34d56b3aa1bc4cff0069f"
1829-
},
18301887
"state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
18311888
}
18321889
}
@@ -1860,13 +1917,12 @@ reason
18601917

18611918
> OPTIONAL. Provides a short description of why the Transmitter has updated the
18621919
status.
1920+
1921+
As with any SSF Event, this event has a top-level `sub_id` claim:
18631922

1864-
subject
1923+
sub_id
18651924

1866-
> REQUIRED. Specifies the stream whose status has been updated.
1867-
The value of the `subject` field
1868-
MUST be of format `opaque`, and its `id` value MUST be the unique ID of the
1869-
stream.
1925+
> REQUIRED. The top-level `sub_id` claim specifies the Stream Id for which the status has been updated. The value of the `sub_id` field MUST be of format `opaque`, and its `id` value MUST be the unique ID of the stream.
18701926

18711927
> Note that the subject that identifies a stream itself is always implicitly
18721928
added to the stream and MAY NOT be removed from the stream.
@@ -1879,19 +1935,19 @@ subject
18791935
"iss": "https://transmitter.example.com",
18801936
"aud": "receiver.example.com",
18811937
"iat": 1493856000,
1938+
"sub_id": {
1939+
"format": "opaque",
1940+
"id" : "f67e39a0a4d34d56b3aa1bc4cff0069f"
1941+
},
18821942
"events": {
18831943
"https://schemas.openid.net/secevent/ssf/event-type/stream-updated": {
1884-
"subject": {
1885-
"format": "opaque",
1886-
"id" : "f67e39a0a4d34d56b3aa1bc4cff0069f"
1887-
},
18881944
"status": "paused",
18891945
"reason": "Internal error"
18901946
}
18911947
}
18921948
}
18931949
~~~
1894-
{: title="Example: Stream Updated SET with stream as the subject of single-stream Transmitter" #figstreamupdatedstreamset}
1950+
{: title="Example: Stream Updated SET" #figstreamupdatedset}
18951951

18961952
# Authorization {#management-api-auth}
18971953
HTTP API calls from a Receiver to a Transmitter SHOULD be authorized by
@@ -2008,9 +2064,7 @@ This section provides SSF profiling specifications for the Security Event Token
20082064
The signature key can be obtained through "jwks_uri", see {{discovery}}.
20092065

20102066
### SSF Event Subject {#event-subjects}
2011-
The subject of a SSF event is identified by the "subject" claim within the event
2012-
payload, whose value is a Subject Identifier. The "subject" claim is REQUIRED
2013-
for all SSF events. The JWT "sub" claim MUST NOT be present in any SET containing
2067+
The primary Subject Member of SSF events is described in the "Subject Members" section ({{subject-ids}}). The JWT "sub" claim MUST NOT be present in any SET containing
20142068
a SSF event.
20152069

20162070
### SSF Event Properties {#event-properties}
@@ -2023,6 +2077,10 @@ specific to the event type.
20232077
"jti": "756E69717565206964656E746966696572",
20242078
"iat": 1520364019,
20252079
"aud": "636C69656E745F6964",
2080+
"sub_id": {
2081+
"format": "phone",
2082+
"phone_number": "+1 206 555 0123"
2083+
},
20262084
"events": {
20272085
"https://schemas.openid.net/secevent/risc/event-type/account-disabled": {
20282086
"subject": {
@@ -2043,6 +2101,10 @@ specific to the event type.
20432101
"jti": "756E69717565206964656E746966696572",
20442102
"iat": 1520364019,
20452103
"aud": "636C69656E745F6964",
2104+
"sub_id": {
2105+
"format": "email",
2106+
"email": "user@example.com"
2107+
},
20462108
"events": {
20472109
"https://schemas.openid.net/secevent/caep/event-type/token-claims-changed": {
20482110
"subject": {

0 commit comments

Comments
 (0)